The InterviewSession is the core component of an Interview Session. It is responsible for managing the data held within the rule session, creating screens and driving interview flows. As such, it is common to interact with this object when building extensions. This following information describes some of the common things you may wish to use the interview session for.
Most importantly, from a extension perspective, the InterviewSession object contains the current data of the session interview (the Instance Data) as well as data about the interview's rulebase (the Rulebase Model Data). The InterviewSession object exists in the Interview Engine Layer.
The following diagram demonstrates the class hierarchy and domains:
The InterviewSession object has many other members - it encapsulates session state data in the Determinations Engine layer. But for this section we will focus on its Session member and indirectly the Rulebase object (via its InterviewRulebase member) because those two objects contain the instance data and rulebase model data of the current Web Determinations Interview.
For more information on how the Interview Session, and the Interview Engine API works in general see Create a custom interview user experience.
The InterviewSession object is accessible to some plugins and Event Handlers that require access to instance data and/or rulebase model data to provide functionality.
It is important to understand the InterviewSession object as this object contains both Rulebase Model Data and Instance Data. Thus it is used by many plugins and Event Handlers.
The Rulebase Model Data is encapsulated in the Rulebase object (com.oracle.determinations.engine.Rulebase). The Rulebase object is accessible if the Web Determinations extension has access to the SessionContext object, InterviewSession object, or InterviewRulebase object.
The basic hierarchy in the Rulebase is that the Rulebase object contains a list of Entity objects. Each Entity object contains all the Attribute and Relationship objects with which it is associated. This hierarchy matches the hierarchy of rule authoring in Oracle Policy Modeling - each attribute and relationship is always related to an entity.
With knowledge of the above hierarchy, the most basic way to access each entity and each attribute and relationship of an entity would be by looping through each entity, and retrieving and looping through attributes and relationships for each entity. See sample code below.
public InterviewUserData load(SecurityToken token, String caseID,
InterviewRulebase rulebase)
{
Rulebase rule = rulebase.getRulebase();
System.out.println("Rulebase: " + rule.getBaseFileName());
//Loop through all Entities of the current Rulebase
List<Entity> entities = rule.getEntities();
for(Entity entity : entities)
{
System.out.println("Entity: " + entity.getName());
//Loop through all Attributes of the current Entity
List<Attribute> entityAttributes = entity.getAttributes();
for(Attribute attribute : entityAttributes)
{
System.out.println("Attribute Name: " + attribute.getName());
//Loop through all Custom Properties of the current Attribute
Map<String, String> attributeProperties = attribute.getProperties();
Set attributePropKeys = attributeProperties.keySet();
Iterator keyIterator = attributePropKeys.iterator();
System.out.println("==Attribute Properties==");
while(keyIterator.hasNext())
{
String key = (String)keyIterator.next();
String value = (String)attributeProperties.get(key);
System.out.println("Property key: " + key + ", Property value: " + value);
}
}
//Loop through all Relationships of the current Entity
List<Relationship> entityRelationships = entity.getRelationships();
for(Relationship relationship : entityRelationships)
{
System.out.println("Relationship Name: " + relationship.getName());
if(relationship.getSymmetricRelationship() != null)
{
System.out.println("Reverse Relationship Name: " + relationship.getSymmetricRelationship().getName());
}
//Loop through all Custom Properties of the current Relationship
Map<String, String> relationshipProperties = relationship.getProperties();
Set relationshipPropKeys = relationshipProperties.keySet();
Iterator keyIterator = relationshipPropKeys.iterator();
System.out.println("==Relationship Properties==");
while(keyIterator.hasNext())
{
String key = (String)keyIterator.next();
String value = (String)relationshipProperties.get(key);
System.out.println("Property key: " + key + ", Property value: " + value);
}
}
}
...
...
For more information about the Rulebase, Entity, Attribute, and Relationship objects, please consult its API documentation for Java or .NET.
Rulebase object: useful methods - the following is a list of Rulebase object members and also useful methods to access those members.
Note that an Entity Attribute or Entity Relationship object can be accessed directly from the Rulebase object via helper methods, to eliminate having to manually find a specific entity to retrieve an attribute or relationship.
|| Member || Description
|| Access Methods
||
| Global Entity
| This is the Entity object for the Global Entity of the current rulebase
| Entity getGlobalEntity()
|
| Entities | All the Entities of the current rulebase
| List getEntities()
Entity getEntity(String name)
|
| Entity Attribute
| Retrieve a specific Attribute object of an entity
| Attribute getAttribute(String attributeName, String entityName) |
| Entity Relationship
| Retrieve a specific Relationship object of an entity
| Relationship getRelationship(String relationshipName, String entityName)
|
Properties | Key/value pairs associated by the rulebase author to the rulebase for custom functionality |
Map getProperties() String getPropertyValue(String key) |
The Instance Data is encapsulated in the Session object (com.oracle.determinations.engine.Session). The Session object is accessible if the Web Determinations extension has access to the SessionContext object, or the InterviewSession object.
The various Instance Data objects are as follows:
Accessing Instance Data is different to Rulebase Model Data - the Instance Data inside the session is not accessible directly. The most common way to access Instance Data is to use the Rulebase Model data object (Entity, Attribute, or Relationship) and pass session data to their methods (either Session or EntityInstance). This is explained in more detail in the subsections below.
There are two ways to access Entity Instance Data.
The following Class diagram shows methods in the Entity and Session object that retrieve EntityInstance objects; refer to the topic Sample code - using Instance Data for actual code usage:
There is only one way to access Attribute Instance Data (Attribute value), and it is by using the Attribute object, passing an EntityInstance, and retrieving the value of the attribute for the EntityInstance object passed. See the sample code below and also the section below, Sample code - using Instance Data.
//Get Entity Instance
Entity entity1 = rulebase.getEntity("entity1");
EntityInstance entity1Instance = entity1.getEntityInstance(session, 1);
//Get Attribute value
Attribute attribute1 = entity1.getAttribute("attribute1");
As mentioned previously - Relationship Instance Data cannot be retrieved. Rather it is a matter of retrieving Target EntityInstance(s) by providing the Source EntityInstance - or vice versa, retrieving Source EntityInstance(s) by providing the TargetEntityInstance. See the sample code below and also the section below, Sample code - Using Instance Data.
//Get Entity Instance
Entity entity1 = rulebase.getEntity("entity1");
EntityInstance entity1Instance = entity1.getEntityInstance(session, 1);
//Get Relationships for the Entity where the Entity is the Source, then get its Target EntityInstances
List<Relationship> sourceRelationships = entity1.getRelationships();
for(Relationship sourceRelationship : sourceRelationships)
{
List<EntityInstance> targetEntityInstances = sourceRelationship.getAllTargets(entity1Instance);
}
Below is sample code that combines all the sample code for Entity, Attribute, and Relationship Instance Data and uses them together.
public String save(SecurityToken token, String requestCaseID,
InterviewSession session) {
Session ruleEngineSession = session.getRuleSession();
Rulebase rulebase = ruleEngineSession.getRulebase();
//Loop through all Entities of the current Rulebase
List<Entity> entities = rulebase.getEntities();
for(Entity entity : entities)
{
//Get all EntityInstances of the current Entity, and loop through them
List<EntityInstance> entityInstances = (List<EntityInstance>)entity.getEntityInstances(ruleEngineSession);
for(EntityInstance entityInstance : entityInstances)
{
//Get all Attributes and their values for the current EntityInstance
List<Attribute> attributes = entity.getAttributes();
for(Attribute attribute : attributes )
{
Object attributeValue = attribute.getValue(entityInstance);
}
//Get all Relationships of the current Entity where the Entity is the Source, and loop through
List<Relationship> sourceRelationships = entity.getRelationships();
for(Relationship relationship : sourceRelationships )
{
//For each relationship retrieve the Source or Target EntityInstances
if(relationship.getRelationshipType().isSingleTarget())
{
EntityInstance targetInstance = relationship.getTarget(entityInstance);
}
else
{
List<EntityInstance> targetInstances = relationship.getAllTargets(entityInstance);
}
}
}
...
...
As mentioned in the overview and in Using the Instance Data, the Instance Data from a Web Determinations interview lives within the Session object in the Determinations Engine Layer.
Modification to the Instance Data inside the Session object is different to accessing/retrieving the Instance Data. It is done via transactions, and the changes to be made to the Instance Data are encapsulated inside an object.
Modifying the Instance Data inside the Session object is done indirectly via the two objects below:
The following are class diagrams for the RuleSessionManager and InterviewUserData objects. Only class members pertinent to modification of Instance Data is displayed:
The most common process for using InterviewUserData is as follows:
An example of how to use the InterviewUserData object to modify Instance Data is demonstrated by the Web Determinations Data Adaptor extension and its load() method. The load() method allows Instance Data from a datasource to be loaded into the interview session before the user starts the interview (see Data Adaptor Plugin).
When Web Determinations calls the Data Adaptor load() method, it creates, populates, and returns an InterviewUserData object that represents the Instance Data to be loaded. Web Determinations then passes the InterviewUserData object to the RuleSessionManager.setData() so the Instance Data can be loaded into the Session object (which would have no Instance Data since it's newly started).
Note: Because DataAdaptor load() is always performed to a newly created Session object, modifications to the Instance Data (signified by the 'Perform Modifications to Session' message) will all be additions instead of additions/modifications/deletions since there is no Instance Data in the Session object to modify or delete.
For information on how to create an InterviewUserData object see Construct the InterviewUserData.